

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>create_atoms command &mdash; LIGGGHTS v3.X documentation</title>
  

  
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  

  
    <link rel="top" title="LIGGGHTS v3.X documentation" href="index.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="Manual.html" class="icon icon-home"> LIGGGHTS
          

          
          </a>

          
            
            
              <div class="version">
                v3.X
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_input_script.html">3. Input Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">4. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_gran_models.html">5. Contact models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_mesh_modules.html">6. Mesh modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">7. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">8. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">10. Python interface to LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">11. Errors</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="Manual.html">LIGGGHTS</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="Manual.html">Docs</a> &raquo;</li>
        
      <li>create_atoms command</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/create_atoms.txt" rel="nofollow"> View page source</a>
          
          <a href="http://www.cfdem.com"> Website</a>
          
            <a href="Section_commands.html#comm" rel="nofollow"> Commands</a>
            
          
        
      </li>
    
  </ul>

  
  <hr/>
  
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="create-atoms-command">
<span id="index-0"></span><h1>create_atoms command<a class="headerlink" href="#create-atoms-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>create_atoms type style args keyword values ...
</pre></div>
</div>
<ul class="simple">
<li>type = atom type (1-Ntypes) of atoms to create</li>
<li>style = <em>box</em> or <em>region</em> or <em>single</em> or <em>random</em></li>
</ul>
<pre class="literal-block">
<em>box</em> args = none
<em>region</em> args = region-ID
  region-ID = atoms will only be created if contained in the region
<em>single</em> args = x y z
  x,y,z = coordinates of a single atom (distance units)
<em>random</em> args = N seed region-ID
  N = number of atoms to create
  seed = random # seed (prime number greater 10000)
  region-ID = create atoms within this region, use NULL for entire simulation box
</pre>
<ul class="simple">
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>basis</em> or <em>remap</em> or <em>units</em> or <em>all_in</em></li>
</ul>
<pre class="literal-block">
<em>basis</em> values = M itype
  M = which basis atom
  itype = atom type (1-N) to assign to this basis atom
<em>remap</em> value = <em>yes</em> or <em>no</em>
<em>units</em> value = <em>lattice</em> or <em>box</em>
  <em>lattice</em> = the geometry is defined in lattice units
  <em>box</em> = the geometry is defined in simulation box units
<em>all_in</em> value = all_in_dist
  all_in_dist = distance from region boundary for insertion
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>create_atoms 1 box
create_atoms 3 region regsphere basis 2 3
create_atoms 3 single 0 0 5
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>This command creates atoms on a lattice, or a single atom, or a random
collection of atoms, as an alternative to reading in their coordinates
explicitly via a <a class="reference internal" href="read_data.html"><em>read_data</em></a> or
<a class="reference internal" href="read_restart.html"><em>read_restart</em></a> command.  A simulation box must
already exist, which is typically created via the
<a class="reference internal" href="create_box.html"><em>create_box</em></a> command.  Before using this command, a
lattice must also be defined using the <a class="reference internal" href="lattice.html"><em>lattice</em></a> command.
The only exceptions are for the <em>single</em> style with units = box or the
<em>random</em> style.</p>
<p>For the <em>box</em> style, the create_atoms command fills the entire
simulation box with atoms on the lattice.  If your simulation box is
periodic, you should insure its size is a multiple of the lattice
spacings, to avoid unwanted atom overlaps at the box boundaries.  If
your box is periodic and a multiple of the lattice spacing in a
particular dimension, LIGGGHTS(R)-PUBLIC is careful to put exactly one atom at the
boundary (on either side of the box), not zero or two.</p>
<p>For the <em>region</em> style, the geometric volume is filled that is inside
the simulation box and is also consistent with the region volume.  See
the <a class="reference internal" href="region.html"><em>region</em></a> command for details.  Note that a region can
be specified so that its &#8220;volume&#8221; is either inside or outside a
geometric boundary.  Also note that if your region is the same size as
a periodic simulation box (in some dimension), LIGGGHTS(R)-PUBLIC does not
implement the same logic as with the <em>box</em> style, to insure exactly
one atom at the boundary.  if this is what you desire, you should
either use the <em>box</em> style, or tweak the region size to get precisely
the atoms you want. With the optional <em>all_in</em> keyword, it can additionally
be specified that the particles should be inserted a certain distance
(as specified by <em>all_in_dist</em>) away from the region boundaries.
<em>all_in</em> is only implemented for <em>region</em> insertion</p>
<p>For the <em>single</em> style, a single atom is added to the system at the
specified coordinates.  This can be useful for debugging purposes or
to create a tiny system with a handful of atoms at specified
positions.</p>
<p>For the <em>random</em> style, N atoms are added to the system at randomly
generated coordinates, which can be useful for generating an amorphous
system.  The atoms are created one by one using the speficied random
number <em>seed</em>, resulting in the same set of atom coordinates,
independent of how many processors are being used in the simulation.
If the <em>region-ID</em> argument is specified as NULL, then the created
atoms will be anywhere in the simulation box.  If a <em>region-ID</em> is
specified, a geometric volume is filled that is inside the simulation
box and is also consistent with the region volume.  See the
<a class="reference internal" href="region.html"><em>region</em></a> command for details.  Note that a region can be
specified so that its &#8220;volume&#8221; is either inside or outside a geometric
boundary.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The atoms generated by the <em>random</em> style will
typically be highly overlapped which will cause many interatomic
potentials to compute large energies and forces.  Thus you should
either perform an <code class="xref doc docutils literal"><span class="pre">energy</span> <span class="pre">minimization</span></code> or run dynamics
with <a class="reference internal" href="fix_nve_limit.html"><em>fix nve/limit</em></a> to equilibrate such a system,
before running normal dynamics.</p>
</div>
<p>The <em>basis</em> keyword specifies an atom type that will be assigned to
specific basis atoms as they are created.  See the
<a class="reference internal" href="lattice.html"><em>lattice</em></a> command for specifics on how basis atoms are
defined for the unit cell of the lattice.  By default, all created
atoms are assigned the argument <em>type</em> as their atom type.</p>
<p>The <em>remap</em> keyword only applies to the <em>single</em> style.  If it is set
to <em>yes</em>, then if the specified position is outside the simulation
box, it will mapped back into the box, assuming the relevant
dimensions are periodic.  If it is set to <em>no</em>, no remapping is done
and no atom is created if its position is outside the box.</p>
<p>The <em>units</em> keyword determines the meaning of the distance units used
to specify the coordinates of the one atom created by the <em>single</em>
style.  A <em>box</em> value selects standard distance units as defined by
the <a class="reference internal" href="units.html"><em>units</em></a> command, e.g. Angstroms for units = real or
metal.  A <em>lattice</em> value means the distance units are in lattice
spacings.</p>
<p>Note that this command adds atoms to those that already exist.  By
using the create_atoms command multiple times, multiple sets of atoms
can be added to the simulation.  For example, interleaving
create_atoms with <a class="reference internal" href="lattice.html"><em>lattice</em></a> commands specifying different
orientations, grain boundaries can be created.  By using the
create_atoms command in conjunction with the
<a class="reference internal" href="delete_atoms.html"><em>delete_atoms</em></a> command, reasonably complex
geometries can be created.  The create_atoms command can also be used
to add atoms to a system previously read in from a data or restart
file.  In all these cases, care should be taken to insure that new
atoms do not overlap existing atoms inappropriately.  The
<a class="reference internal" href="delete_atoms.html"><em>delete_atoms</em></a> command can be used to handle
overlaps.</p>
<p>Atom IDs are assigned to created atoms in the following way.  The
collection of created atoms are assigned consecutive IDs that start
immediately following the largest atom ID existing before the
create_atoms command was invoked.  When a simulation is performed on
different numbers of processors, there is no guarantee a particular
created atom will be assigned the same ID.</p>
<p>Aside from their ID, atom type, and xyz position, other properties of
created atoms are set to default values, depending on which quantities
are defined by the chosen <a class="reference internal" href="atom_style.html"><em>atom style</em></a>.  See the <a class="reference internal" href="atom_style.html"><em>atom style</em></a> command for more details.  See the
<a class="reference internal" href="set.html"><em>set</em></a> and <a class="reference internal" href="velocity.html"><em>velocity</em></a> commands for info on how
to change these values.</p>
<ul class="simple">
<li>charge = 0.0</li>
<li>diameter = 1.0</li>
<li>shape = 0.0 0.0 0.0</li>
<li>density = 1.0</li>
<li>volume = 1.0</li>
<li>velocity = 0.0 0.0 0.0</li>
<li>angular velocity = 0.0 0.0 0.0</li>
<li>angular momentum = 0.0 0.0 0.0</li>
<li>quaternion = (1,0,0,0)</li>
<li>bonds  = none</li>
</ul>
<p>Note that the <em>sphere</em> atom style sets the default particle diameter
to 1.0 as well as the density.  This means the mass for the particle
is not 1.0, but is PI/6 * diameter^3 = 0.5236.</p>
<p>Note that the <em>ellipsoid</em> atom style sets the default particle shape
to (0.0 0.0 0.0) and the density to 1.0 which means it is a point
particle, not an ellipsoid, and has a mass of 1.0.</p>
<p>The <a class="reference internal" href="set.html"><em>set</em></a> command can be used to override many of these
default settings.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>An <a class="reference internal" href="atom_style.html"><em>atom_style</em></a> must be previously defined to use this
command.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="lattice.html"><em>lattice</em></a>, <a class="reference internal" href="region.html"><em>region</em></a>, <a class="reference internal" href="create_box.html"><em>create_box</em></a>,
<a class="reference internal" href="read_data.html"><em>read_data</em></a>, <a class="reference internal" href="read_restart.html"><em>read_restart</em></a></p>
</div>
<div class="section" id="default">
<h2>Default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>The default for the <em>basis</em> keyword is that all created atoms are
assigned the argument <em>type</em> as their atom type.  The default for
<em>remap</em> = no and for <em>units</em> = box.</p>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2016, DCS Computing GmbH, JKU Linz and Sandia Corporation.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'v3.X',
            LANGUAGE:'None',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: ''
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>